How to use HSP Docs Library, how to write documents

HSP Docs Library (HDL) is a browser for searching and browsing HSP documents at once.

hs Help files, txt / HTML documents, sample scripts can be searched in bulk or cross-referenced.

Files read by HSP Docs Library

The files in the

library are searched for in the following directories:

Directory	Files to be searched
doclib	.hs .txt .htm .html *.hsp
hsphelp	*.hs
sample	*.hsp
common	* .as * .hsp (documented header file)

If you want to add new documentation to the HDL library, place the files in the doclib directory.

For each plugin or module, create a category directory under the doclib directory and create a category directory. If you put together related documents (hs, hsp samples, txt, HTML documents and images used in them, style sheets, etc.), It will be easier to manage even if the number of files increases.

Shift_JIS and UTF-8 are supported for the character code of the

document. This document is stored in UTF-8.

HSP Docs Library Documentation Section

In HDL, the set of loaded files is called a library. The library is command help , documentation , sample It is divided into three sections. Each section is further subdivided into categories. Below the category is the page that is the body of the content. The contents of the

.hs help file are distributed to the Command Help section. The categories in the command help section are divided according to the plugin used.

The

.txt .htm .html file is sorted into the Documents section.

The

.hsp files are distributed in the Samples section. The categories in the document section and the sample section are separated by the name of the directory where the files are actually located. Files that do not belong to a subdirectory fall into the "default" category.

If there is a documented header file (.as .hsp) in the common directory, its contents will be sorted to the command help section.

How to create hs file

HDL supports HSP's own hs format help file as a help file for command help manuals. See HS_BIBLE.txt for the format of the

hs file.

hs file inline HTML

In HDL, directly between the line written "html {" and the line written "} html" in the% inst field of the hs file. There is a feature called "inline HTML" that displays as HTML.

This is a display specification of HDL, not a specification as an hs file, and some HTML representations can be used in the hs file.

; hs file format example

%index
stickf
Get keystroke information

%inst
The stickf function returns an OR value for multiple key states, such as:
html{
<table border=1>
& lt; tr & gt; & lt; th & gt; Value & lt; / th & gt; & lt; th & gt; Key & lt; / th & gt; & lt; / tr & gt;
& lt; tr & gt; & lt; td & gt; 1 & lt; / td & gt; & lt; td & gt; Cursor key left (<-) & lt; / td & gt; & lt; / tr & gt;
& lt; tr & gt; & lt; td & gt; 2 & lt; / td & gt; & lt; td & gt; On the cursor key (↑) & lt; / td & gt; & lt; / tr & gt;
& lt; tr & gt; & lt; td & gt; 4 & lt; / td & gt; & lt; td & gt; Cursor key right (->) & lt; / td & gt; & lt; / tr & gt;
& lt; tr & gt; & lt; td & gt; 8 & lt; / td & gt; & lt; td & gt; Cursor down (↓) & lt; / td & gt; & lt; / tr & gt;
& lt; tr & gt; & lt; td & gt; 16 & lt; / td & gt; & lt; td & gt; Spacebar & lt; / td & gt; & lt; / tr & gt;
& lt; tr & gt; & lt; td & gt; 32 & lt; / td & gt; & lt; td & gt; Enter key & lt; / td & gt; & lt; / tr & gt;
& lt; tr & gt; & lt; td & gt; 64 & lt; / td & gt; & lt; td & gt; Ctrl key & lt; / td & gt; & lt; / tr & gt;
& lt; tr & gt; & lt; td & gt; 128 & lt; / td & gt; & lt; td & gt; ESC key & lt; / td & gt; & lt; / tr & gt;
</table>
}html

For inline HTML sections, the HTML format inside is not checked by HDL. If incorrect HTML is written, the layout of the entire page may be corrupted, so be sure to check it carefully when distributing hs data. Also, avoid using HTML for decorative purposes that are not relevant to the meaning of the information.

Do not write active scripts (javascript, etc.) in inline HTML. Some keywords related to script execution are restricted in use. The style of the elements used in inline HTML can be influenced by external CSS. The document type for the

HDL output page is HTML 5 .

(Not recommended due to complexity) Header file and hs doc comment

HDL reads header files (.as .hsp) under the common directory as documented header files . A

documented header file is a header file with documentation comments in hs format added. A file that has both a function as a header file and a function as a command help manual.

When writing a doc comment in an HSP script, use a format like the one below. This script meets its specifications, both as an HSP script and as an hs help file, and works correctly in either format.

;============================================================
Header file with doc comment
;============================================================
 / * ~ Module information (hs default record)
%dll
dxmodule

%ver
1.67

%date
2008/05/01

% * / ; <--- After this, it will be a comment as an hs file.
;------------------------------------------------------------

#module

;===========================================================
 / * ~ Document part
%index
dxsetcam
Camera position setting

%prm
x1, y1, z1, x2, y2, z2

%inst
Set the camera coordinates x1, y1, z1 and orientation (target position x2, y2, z2).

%group
3D control instructions

%*/
;------------------------------------------------------------
; ~ Implementation part
#deffunc dxsetcam double p1, double p2, double p3, double p4, double p5, double p6
	//
	return
//
#global

The doc comment is described in the multi-line comment (/ * ~ * /) of the HSP script according to the format specifications of the hs help file. This multi-line comment containing hs-formatted field tags is called a document block .

Use the% symbol at the end of the document block so that subsequent comments are in hs format. In hs format, if there is an undefined field tag, the following lines are considered comments. If you forget to do this, even the HSP script part may be recognized as part of the hs document.

It is recommended to write one of the following for the description of this part.

%*/

%rem
*/

A multi-line comment (/ * ~ * /) cannot be expressed as a document in a document block.

Files written according to this rule only need to change the extension to .hs. It can also be read from hs help tools that do not support doc comments.

Request to document creator

When creating documents and sample scripts, keep the following points in mind to improve visibility and searchability.

Give the HTML document an appropriate title

The content of the title tag in the

HTML file is recognized as the title of the document. The title should be easy to understand what the content of the document is.

Give texts and sample scripts descriptive file names

The title of the sample script or txt file is the file name. Filenames like "test1.hsp" should be avoided as you cannot guess what they are.

This is also true for sample and document directory names (= category names).

hs file line breaks are left to the viewer's automatic wrapping

If you start a new line in the body of the hs file with a fixed number of characters, It may be difficult to read depending on the window size and font size of the viewer. Leave paragraph wrapping to the viewer's window width.

Do not specify fixed width of HTML document

The width of the HTML document should not be fixed to an absolute value, but should be readable even if the browser window width is reduced.

(Reference) Basic form of instruction command help

Regarding the explanation text of the command command help, the following paragraph style seems to tend to make the text simpler and easier to understand.

Paragraph ・ This command does ○○○. (Description of function)

Paragraph ・ Specify ○○○ in p1. This value is. .. .. (Explanation of arguments)

Paragraph ・ Specify ○○○ in p2. This value is. .. .. (Explanation of arguments)

Paragraph ・ The points to note with this command are: .. .. (Explanation of precautions and restrictions)

Paragraph ・ If this instruction is successful, the system variable stat will be displayed. .. .. (Explanation of return value)

Bad example

dxsetlocal

This instruction uses a coordinate transformation matrix specified by px to pz and m00 to m22, except for dxsetcam. Set as the local coordinate system that applies to all dxmodule instructions.

… × Sentence structure is complicated

A good example

dxsetlocal

Set the local coordinate system.

Specify the coordinate transformation matrix with px ~ pz, m00 ~ m22.

The local coordinate system applies to all dxmodule instructions except dxsetcam.

… ○ Easy

Update information

The latest version of HDL is available on s.programe net http://spn.php.xdomain.jp/ It has been.